Purpose

WildFly provides EJB client API project as well as remote-naming project for invoking on remote objects exposed via JNDI. This article explains which approach to use when and what the differences and scope of each of these projects is.

History

Previous versions of JBoss AS (versions < WildFly 8) used JNP project (http://anonsvn.jboss.org/repos/jbossas/projects/naming/) as the JNDI naming implementation. Developers of client applications of previous versions of JBoss AS will be familiar with the jnp:// PROVIDER_URL URL they used to use in their applications for communicating with the JNDI server on the JBoss server.

Starting WildFly 8, the JNP project is not used. Neither on the server side nor on the client side. The client side of the JNP project has now been replaced by jboss-remote-naming project (https://github.com/jbossas/jboss-remote-naming). There were various reasons why the JNP client was replaced by jboss-remote-naming project. One of them was the JNP project did not allow fine grained security configurations while communicating with the JNDI server. The jboss-remote-naming project is backed by the jboss-remoting project (https://github.com/jboss-remoting/jboss-remoting) which allows much more and better control over security.

Overview

Now that we know that for remote client JNDI communication with WildFly 8 requires jboss-remote-naming project, let's quickly see what the code looks like.

void doLookup() {
  // Create an InitialContext using the javax.naming.* API
  Context ctx = new InitialContext();
  ctx.lookup("foo/bar");
  ...
}

java.naming.factory.initial=org.jboss.naming.remote.client.InitialContextFactory
java.naming.provider.url=http-remoting://localhost:8080

void doLookup() {
  Properties jndiProps = new Properties();
  jndiProps.put(Context.INITIAL_CONTEXT_FACTORY, "org.jboss.naming.remote.client.InitialContextFactory");
  jndiProps.put(Context.PROVIDER_URL,"http-remoting://localhost:8080");
  // create a context passing these properties
  Context ctx = new InitialContext(jndiProps);
  // lookup
  ctx.lookup("foo/bar");
  ...
}

void doLookup() {
  Properties jndiProps = new Properties();
  jndiProps.put(Context.INITIAL_CONTEXT_FACTORY, "org.jboss.naming.remote.client.InitialContextFactory");
  jndiProps.put(Context.PROVIDER_URL,"http-remoting://localhost:8080");
  // username
  jndiProps.put(Context.SECURITY_PRINCIPAL, "peter");
  // password
  jndiProps.put(Context.SECURITY_CREDENTIALS, "lois");
  // create a context passing these properties
  Context ctx = new InitialContext(jndiProps);
  // lookup
  ctx.lookup("foo/bar");
  ...
}

Summary

That pretty much covers whatever is important to know, in the remote-naming project, for a typical client application. Don't close the browser yet though, since we haven't yet come to the part of EJB invocations from a remote client using the remote-naming project. In fact, the motivation behind writing this article was to explain why not to use remote-naming project (in most cases) for doing EJB invocations against WildFly server.

Those of you who don't have client applications doing remote EJB invocations, can just skip the rest of this article if you aren't interested in those details.

Remote EJB invocations backed by the remote-naming project

In previous sections of this article we saw that whatever is exposed in the java:jboss/exported/ namespace is accessible remotely to the client applications under the relative JNDI name. Some of you might already have started thinking about exposing remote views of EJBs under that namespace.

It's important to note that WildFly server side already by default exposes the remote views of a EJB under the java:jboss/exported/ namespace (although it isn't logged in the server logs). So assuming your server side application has the following stateless bean:

package org.myapp.ejb;

@Stateless
@Remote(Foo.class)
public class FooBean implements Foo {
...
 public String sayBar() {
     return "Baaaaaaaar";
 }
}

Then the "Foo" remote view is exposed under the java:jboss/exported/ namespace under the following JNDI name scheme (which is similar to that mandated by EJB3.1 spec for java:global/ namespace):app-name

app-name/module-name/bean-name!bean-interface

where,

app-name = the name of the .ear (without the .ear suffix) or the application name configured via application.xml deployment descriptor. If the application isn't packaged in a .ear then there will be no app-name part to the JNDI string.
module-name = the name of the .jar or .war (without the .jar/.war suffix) in which the bean is deployed or the module-name configured in web.xml/ejb-jar.xml of the deployment. The module name is mandatory part in the JNDI string.
bean-name = the name of the bean which by default is the simple name of the bean implementation class. Of course it can be overridden either by using the "name" attribute of the bean definining annotation (@Stateless(name="blah") in this case) or even the ejb-jar.xml deployment descriptor.
bean-interface = the fully qualified class name of the interface being exposed by the bean.

So in our example above, let's assume the bean is packaged in a myejbmodule.jar which is within a myapp.ear. So the JNDI name for the Foo remote view under the java:jboss/exported/ namespace would be:

java:jboss/exported/myapp/myejbmodule/FooBean!org.myapp.ejb.Foo

That's where WildFly will automatically expose the remote views of the EJBs under the java:jboss/exported/ namespace, in addition to the java:global/ java:app/ java:module/ namespaces mandated by the EJB 3.1 spec.

So the next logical question would be, are these remote views of EJBs accessible and invokable using the remote-naming project on the client application. The answer is yes! Let's quickly see the client code for invoking our FooBean. Again, let's just use "peter" and "lois" as username/pass for connecting to the remoting connector.

void doBeanLookup() {
  ...
  Properties jndiProps = new Properties();
  jndiProps.put(Context.INITIAL_CONTEXT_FACTORY, "org.jboss.naming.remote.client.InitialContextFactory");
  jndiProps.put(Context.PROVIDER_URL,"http-remoting://localhost:8080");
  // username
  jndiProps.put(Context.SECURITY_PRINCIPAL, "peter");
  // password
  jndiProps.put(Context.SECURITY_CREDENTIALS, "lois");
  // This is an important property to set if you want to do EJB invocations via the remote-naming project
  jndiProps.put("jboss.naming.client.ejb.context", true);
  // create a context passing these properties
  Context ctx = new InitialContext(jndiProps);
  // lookup the bean     Foo
  beanRemoteInterface = (Foo) ctx.lookup("myapp/myejbmodule/FooBean!org.myapp.ejb.Foo");
  String bar = beanRemoteInterface.sayBar();
  System.out.println("Remote Foo bean returned " + bar);
  ctx.close();
  // after this point the beanRemoteInterface is not longer valid!
}

As you can see, most of the code is similar to what we have been seeing so far for setting up a JNDI context backed by the remote-naming project. The only parts that change are:

1) An additional "jboss.naming.client.ejb.context" property that is added to the properties passed to the InitialContext constructor.
2) The JNDI name used for the lookup
3) And subsequently the invocation on the bean interface returned by the lookup.

Let's see what the "jboss.naming.client.ejb.context" does. In WildFly, remote access/invocations on EJBs is facilitated by the JBoss specific EJB client API, which is a project on its own https://github.com/jbossas/jboss-ejb-client. So no matter, what mechanism you use (remote-naming or core EJB client API), the invocations are ultimately routed through the EJB client API project. In this case too, the remote-naming internally uses EJB client API to handle EJB invocations. From a EJB client API project perspective, for successful communication with the server, the project expects a EJBClientContext backed by (atleast one) EJBReceiver(s). The EJBReceiver is responsible for handling the EJB invocations. One type of a EJBReceiver is a RemotingConnectionEJBReceiver which internally uses jboss-remoting project to communicate with the remote server to handle the EJB invocations. Such a EJBReceiver expects a connection backed by the jboss-remoting project. Of course to be able to connect to the server, such a EJBReceiver would have to know the server address, port, security credentials and other similar parameters. If you were using the core EJB client API, then you would have configured all these properties via the jboss-ejb-client.properties or via programatic API usage as explained here EJB invocations from a remote client using JNDI. But in the example above, we are using remote-naming project and are not directly interacting with the EJB client API project.

If you look closely at what's being passed, via the JNDI properties, to the remote-naming project and if you remember the details that we explained in a previous section about how the remote-naming project establishes a connection to the remote server, you'll realize that these properties are indeed the same as what the RemotingConnectionEJBReceiver would expect to be able to establish the connection to the server. Now this is where the "jboss.naming.client.ejb.context" property comes into picture. When this is set to true and passed to the InitialContext creation (either via jndi.properties or via the constructor of that class), the remote-naming project internally will do whatever is necessary to setup a EJBClientContext, containing a RemotingConnectionEJBReceiver which is created using the same remoting connection that is created by and being used by remote-naming project for its own JNDI communication usage. So effectively, the InitialContext creation via the remote-naming project has now internally triggered the creation of a EJBClientContext containing a EJBReceiver capable of handling the EJB invocations (remember, no remote EJB invocations are possible without the presence of a EJBClientContext containing a EJBReceiver which can handle the EJB).

So we now know the importance of the "jboss.naming.client.ejb.context" property and its usage. Let's move on the next part in that code, the JNDI name. Notice that we have used the JNDI name relative to the java:jboss/exported/ namespace while doing the lookup. And since we know that the Foo view is exposed on that JNDI name, we cast the returned object back to the Foo interface. Remember that we earlier explained how each lookup via remote-naming triggers a server side communication and a marshalling/unmarshalling process. This applies for EJB views too. In fact, the remote-naming project has no clue (since that's not in the scope of that project to know) whether it's an EJB or some random object.

Once the unmarshalled object is returned (which actually is a proxy to the bean), the rest is straightforward, we just invoke on that returned object. Now since the remote-naming implementation has done the necessary setup for the EJBClientContext (due to the presence of "jboss.naming.client.ejb.context" property), the invocation on that proxy will internally use the EJBClientContext (the proxy is smart enough to do that) to interact with the server and return back the result. We won't go into the details of how the EJB client API handles the communication/invocation.

Long story short, using the remote-naming project for doing remote EJB invocations against WildFly is possible!

Why use the EJB client API approach then?

I can guess that some of you might already question why/when would one use the EJB client API style lookups as explained in the EJB invocations from a remote client using JNDI article instead of just using (what appears to be a simpler) remote-naming style lookups.

Before we answer that, let's understand a bit about the EJB client project. The EJB client project was implemented keeping in mind various optimizations and features that would be possible for handling remote invocations. One such optimization was to avoid doing unnecessary server side communication(s) which would typically involve network calls, marshalling/unmarshalling etc... The easiest place where this optimization can be applied, is to the EJB lookup. Consider the following code (let's ignore how the context is created):

ctx.lookup("foo/bar");

Now foo/bar JNDI name could potentially point to any type of object on the server side. The jndi name itself won't have the type/semantic information of the object bound to that name on the server side. If the context was setup using the remote-naming project (like we have seen earlier in our examples), then the only way for remote-naming to return an object for that lookup operation is to communicate with the server and marshal/unmarshal the object bound on the server side. And that's exactly what it does (remember, we explained this earlier).

The EJB client API project on the other hand optimizes this lookup. In order to do so, it expects the client application to let it know that a EJB is being looked up. It does this, by expecting the client application to use the JNDI name of the format "ejb:" namespace and also expecting the client application to setup the JNDI context by passing the "org.jboss.ejb.client.naming" value for the Context.URL_PKG_PREFIXES property.

Example:

final Properties jndiProperties = new Properties();
jndiProperties.put(Context.URL_PKG_PREFIXES, "org.jboss.ejb.client.naming");
// create the context
final Context context = new InitialContext(jndiProperties);

// lookup
Foo beanProxy = context.lookup("ejb:myapp/myejbmodule//FooBean!org.myapp.ejb.Foo");
String bar = beanProxy.sayBar();

More details about such code can be found here EJB invocations from a remote client using JNDI

When a client application looks up anything under the "ejb:" namespace, it is a clear indication (for the EJB client API project) to know that the client is looking up an EJB. That's where it steps in to do the necessary optimizations that might be applicable. So unlike, in the case of remote-naming project (which has no clue about the semantics of the object being looked up), the EJB client API project does not trigger a server side communication or a marshal/unmarshal process when you do lookup for a remote view of a stateless bean (it's important to note that we have specifically mentioned stateless bean here, we'll come to that later). Instead, the EJB client API just returns a java.lang.reflect.Proxy instance of the remote view type that's being looked up. This not just saves a network call, marshalling/unmarshalling step but it also means that you can create an EJB proxy even when the server isn't up yet. Later on, when the invocation on the proxy happens, the EJB client API does communicate with the server to carry out the invocation.

context.lookup("ejb:myapp/myejbmodule//StatefulBean!org.myapp.ejb.Counter?stateful");